postcss-media-query-parser

What is postcss-media-query-parser?

The postcss-media-query-parser package is a PostCSS plugin that allows you to parse and manipulate CSS media queries. It provides a way to analyze, modify, and work with media queries in your CSS files programmatically.

What are postcss-media-query-parser's main functionalities?

Parsing Media Queries

This feature allows you to parse a media query string into an object that you can manipulate. The parsed object contains detailed information about the media query, such as its type, expressions, and values.

const parser = require('postcss-media-query-parser');
const mediaQuery = '@media screen and (min-width: 900px)';
const parsed = parser(mediaQuery);
console.log(parsed);

Modifying Media Queries

This feature allows you to modify the parsed media query object and convert it back to a string. In this example, the minimum width is changed from 900px to 800px.

const parser = require('postcss-media-query-parser');
const mediaQuery = '@media screen and (min-width: 900px)';
const parsed = parser(mediaQuery);
parsed.nodes[0].value = '800px';
console.log(parsed.toString());

Analyzing Media Queries

This feature allows you to analyze the parsed media query object to check for specific conditions. In this example, it checks if the media query contains a minimum width of 900px.

const parser = require('postcss-media-query-parser');
const mediaQuery = '@media screen and (min-width: 900px)';
const parsed = parser(mediaQuery);
const isMinWidth900 = parsed.nodes.some(node => node.value === '900px');
console.log(isMinWidth900);

Other packages similar to postcss-media-query-parser

postcss-custom-media

The postcss-custom-media package allows you to define custom media queries in your CSS. It is similar to postcss-media-query-parser in that it deals with media queries, but it focuses on creating and using custom media queries rather than parsing and modifying existing ones.

postcss-media-minmax

The postcss-media-minmax package lets you use the simpler syntax for writing media queries with ranges, such as `width >= 500px`. It transforms these queries into standard CSS media queries. While it also deals with media queries, its primary focus is on simplifying the syntax rather than parsing and manipulating them.

postcss-preset-env

The postcss-preset-env package allows you to use modern CSS features, including media queries, and transpile them to be compatible with older browsers. It provides a broader range of functionalities compared to postcss-media-query-parser, which is specifically focused on media queries.

README

postcss-media-query-parser

Media query parser with very simple traversing functionality.

Installation and usage

First install it via NPM:

npm install postcss-media-query-parser

Then in your Node.js application:

import mediaParser from "postcss-media-query-parser";

const mediaQueryString = "(max-width: 100px), not print";
const result = mediaParser(mediaQueryString);

The result will be this object:

{
  // the first media query
  nodes: [{
    type: 'media-query',
    value: '(max-width: 100px)',
    before: '',
    after: '',
    sourceIndex: 0,
    nodes: [{
      type: 'media-feature-expression',
      value: '(max-width: 100px)',
      before: '',
      after: '',
      sourceIndex: 0,
      nodes: [{
        type: 'media-feature',
        value: 'max-width',
        before: '',
        after: '',
        sourceIndex: 1,
      }, {
        type: 'value',
        value: '100px',
        before: ' ',
        after: '',
        sourceIndex: 12,
      }]
    }]
  },
  // the second media query
  {
    type: 'media-query',
    value: 'not print',
    before: ' ',
    after: '',
    sourceIndex: 20,
    nodes: [{
      type: 'keyword',
      value: 'not',
      before: ' ',
      after: ' ',
      sourceIndex: 20,
    }, {
      type: 'media-type',
      value: 'print',
      before: ' ',
      after: '',
      sourceIndex: 24,
    }]
  }]
}

One of the likely sources of a string to parse would be traversing a PostCSS container node and getting the params property of nodes with the name of "atRule":

import postcss from "postcss";
import mediaParser from "postcss-media-query-parser";

const root = postcss.parse(<contents>);
// ... or any other way to get sucn container

root.walkAtRules("media", (atRule) => {
  const mediaParsed = mediaParser(atRule.params);
  // Do something with "mediaParsed" object
});

Nodes

Node is a very generic item in terms of this parser. It's is pretty much everything that ends up in the parsed result. Each node has these properties:

• type: the type of the node (see below);
• value: the node's value stripped of trailing whitespaces;
• sourceIndex: 0-based index of the node start relative to the source start (excluding trailing whitespaces);
• before: a string that contain a whitespace between the node start and the previous node end/source start;
• after: a string that contain a whitespace between the node end and the next node start/source end;

A node can have one of these types (according to the 2012 CSS3 standard):

• media-query-list: that is the root level node of the parsing result. A container; its children can have types of url and media-query.
• url: if a source is taken from a CSS @import rule, it will have a url(...) function call. The value of such node will be url(http://uri-address), it is to be parsed separately.
• media-query: such nodes correspond to each media query in a comma separated list. In the exapmle above there are two. Nodes of this type are containers.
• media-type: screen, tv and other media types.
• keyword: only, not or and keyword.
• media-feature-expression: an expression in parentheses that checks for a condition of a particular media feature. The value would be like this: (max-width: 1000px). Such nodes are containers. They always have a media-feature child node, but might not have a value child node (like in screen and (color)).
• media-feature: a media feature, e.g. max-width.
• value: a media feature expression value, e.g. 100px in (max-width: 1000px).

Parsing details

postcss-media-query-parser allows for cases of some non-standard syntaxes and tries its best to work them around. For example, in a media query from a code with SCSS syntax:

@media #{$media-type} and ( #{"max-width" + ": 10px"} ) { ... }

#{$media-type} will be the node of type media-type, alghough $media-type's value can be only screen. And inside media-feature-expression there will only be a media-feature type node with the value of #{"max-width" + ": 10px"} (this example doesn't make much sense, it's for demo purpose).

But the result of parsing malformed media queries (such as with incorrect amount of closing parens, curly braces, etc.) can be unexpected. For exapmle, parsing:

@media ((min-width: -100px)

would return a media query list with the single media-query node that has no child nodes.

Containers

Containers are nodes that have other nodes as children. Container nodes have an additional property nodes which is an array of their child nodes. And also these methods:

• each(callback) - traverses the direct child nodes of a container, calling callback function for each of them. Returns false if traversing has stopped by means of callback returning false, and true otherwise.
• walk([filter, ]callback) - traverses ALL descendant nodes of a container, calling callback function for each of them. Returns false if traversing has stopped by means of callback returning false, and true otherwise.

In both cases callback takes these parameters:

• node - the current node (one of the container's descendats, that the callback has been called against).
• i - 0-based index of the node in an array of its parent's children.
• nodes - array of child nodes of node's parent.

If callback returns false, the traversing stops.

License

MIT

Changelog

0.1.0

Initial release